home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / g_man / cat3 / standard / rectread.z / rectread
Encoding:
Text File  |  1998-10-20  |  6.8 KB  |  133 lines
  1.  
  2.  
  3.  
  4. rrrreeeeccccttttrrrreeeeaaaadddd((((3333GGGG))))                                                      rrrreeeeccccttttrrrreeeeaaaadddd((((3333GGGG))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      rrrreeeeccccttttrrrreeeeaaaadddd,,,, llllrrrreeeeccccttttrrrreeeeaaaadddd - reads a rectangular array of pixels into CPU memory
  10.  
  11. CCCC SSSSPPPPEEEECCCCIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN
  12.      lllloooonnnngggg rrrreeeeccccttttrrrreeeeaaaadddd((((xxxx1111,,,, yyyy1111,,,, xxxx2222,,,, yyyy2222,,,, ppppaaaarrrrrrrraaaayyyy))))
  13.      SSSSccccrrrreeeeeeeennnnccccoooooooorrrrdddd xxxx1111,,,, yyyy1111,,,, xxxx2222,,,, yyyy2222;;;;
  14.      CCCCoooolllloooorrrriiiinnnnddddeeeexxxx ppppaaaarrrrrrrraaaayyyy[[[[]]]];;;;
  15.  
  16.      lllloooonnnngggg llllrrrreeeeccccttttrrrreeeeaaaadddd((((xxxx1111,,,, yyyy1111,,,, xxxx2222,,,, yyyy2222,,,, ppppaaaarrrrrrrraaaayyyy))))
  17.      SSSSccccrrrreeeeeeeennnnccccoooooooorrrrdddd xxxx1111,,,, yyyy1111,,,, xxxx2222,,,, yyyy2222;;;;
  18.      uuuunnnnssssiiiiggggnnnneeeedddd lllloooonnnngggg ppppaaaarrrrrrrraaaayyyy[[[[]]]];;;;
  19.  
  20. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  21.      _x_1       expects the x coordinate of the lower-left corner of the
  22.               rectangle that you want to read.
  23.  
  24.      _y_1       expects the y coordinate of the lower-left corner of the
  25.               rectangle that you want to read.
  26.  
  27.      _x_2       expects the x coordinate of the upper-right corner of the
  28.               rectangle that you want to read.
  29.  
  30.      _y_2       expects the y coordinate of the upper-right corner of the
  31.               rectangle that you want to read.
  32.  
  33.      _p_a_r_r_a_y   expects the array to receive the pixels that you want to read.
  34.  
  35. FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  36.      The returned value of this function is the number of pixels specified in
  37.      the rectangular region, regardless of whether the pixels were actually
  38.      readable (i.e. on-screen) or not.
  39.  
  40. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  41.      rrrreeeeccccttttrrrreeeeaaaadddd and llllrrrreeeeccccttttrrrreeeeaaaadddd read the pixel values of a rectangular region of
  42.      the screen and write them to the array, _p_a_r_r_a_y. The system fills the
  43.      elements of _p_a_r_r_a_y from left-to-right, then bottom-to-top.  All
  44.      coordinates are relative to the lower-left corner of the window, not the
  45.      screen or viewport.
  46.  
  47.      Pixels are read from the currently active framebuffer, as specified by
  48.      ddddrrrraaaawwwwmmmmooooddddeeee....  Thus, to read pixel values from the overlay bitplanes, for
  49.      example, simply set ddddrrrraaaawwwwmmmmooooddddeeee to OOOOVVVVEEEERRRRDDDDRRRRAAAAWWWW.  Use rrrreeeeaaaaddddssssoooouuuurrrrcccceeee to specify the
  50.      pixel source within the current framebuffer (backbuffer, frontbuffer, or
  51.      z-buffer, for example) from which both rrrreeeeccccttttrrrreeeeaaaadddd and llllrrrreeeeccccttttrrrreeeeaaaadddd take pixel
  52.      values.
  53.  
  54.      rrrreeeeccccttttrrrreeeeaaaadddd fills an array of 16-bit words, and therefore should be used
  55.      only to read color index values.  llllrrrreeeeccccttttrrrreeeeaaaadddd fills an array of 32-bit
  56.      words.  Based on the current ppppiiiixxxxmmmmooooddddeeee, llllrrrreeeeccccttttrrrreeeeaaaadddd can return pixels of 1,
  57.      2, 4, 8, 12, 16, 24, or 32 bits each.  Use llllrrrreeeeccccttttrrrreeeeaaaadddd to read packed RGB
  58.      or RGBA values, color index values, or _z values.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. rrrreeeeccccttttrrrreeeeaaaadddd((((3333GGGG))))                                                      rrrreeeeccccttttrrrreeeeaaaadddd((((3333GGGG))))
  71.  
  72.  
  73.  
  74.      ppppiiiixxxxmmmmooooddddeeee greatly affects the operation of llllrrrreeeeccccttttrrrreeeeaaaadddd, and has no effect on
  75.      the operation of rrrreeeeccccttttrrrreeeeaaaadddd.  By default, llllrrrreeeeccccttttrrrreeeeaaaadddd returns 32-bit pixels
  76.      in the format used by ccccppppaaaacccckkkk.  Different pixel sizes, framebuffer shifts,
  77.      scan patterns through the framebuffer, and offsets through memory, can
  78.      all be specified using ppppiiiixxxxmmmmooooddddeeee
  79.  
  80.      rrrreeeeccccttttrrrreeeeaaaadddd and llllrrrreeeeccccttttrrrreeeeaaaadddd leave the current character position
  81.      unpredictable.
  82.  
  83. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  84.      cpack, drawmode, lrectwrite, pixmode, readsource
  85.  
  86. NNNNOOOOTTTTEEEESSSS
  87.      These routines are available only in immediate mode.
  88.  
  89.      On IRIS-4D GT and GTX models, returned bits that do not correspond to
  90.      valid bitplanes are undefined.  Other models return zero in these bits.
  91.  
  92.      On IRIS-4D GT, GTX, XS, XS24, XZ, Elan, Extreme and VGX models, rrrreeeeccccttttrrrreeeeaaaadddd
  93.      performance will suffer if _x_2 - _x_1 + 1 is odd, or if _p_a_r_r_a_y is not 32-bit
  94.      word aligned.
  95.  
  96.      Due to the write-back nature of the R4000 cache, sproc/m_fork processes
  97.      should avoid accesses to cache lines (128 Bytes) to which a pixel read is
  98.      currently in progress.
  99.  
  100.      The size of the array passed to llllrrrreeeeccccttttrrrreeeeaaaadddd is limited to the size of the
  101.      screen.
  102.  
  103. BBBBUUUUGGGGSSSS
  104.      On IRIS-4D GT and GTX models, when reading pixels from the PUPMODE
  105.      planes, the returned bits are shifted up by two bits.
  106.  
  107.      IRIS-4D VGX and VGXT require that both |x2-x1+1| and |y2-y1+1| be less
  108.      than 2048.
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.